pro atvcircle, radius, x, y, color=color, scaled=scaled, _extra=extra

;+
; NAME:     atvcircle
; PURPOSE:  overplots circles on the ATV display.  Use after running ATV.PRO
; CALLING SEQUENCE:
;           atvcircle, radius, x, y [, color=] [,/scaled]
; INPUTS:   radius -- circle radius in pixels.
;           x      -- scalar or vector of circle center positions in x pixels
;           y      -- scalar or vector of circle center positions in y pixels
; OPTIONAL KEYWORD INPUTS:
;           color  -- string containing a color name (default ATV plot colors), 
;                     or an integer color index:
;                     0 = black  
;                     1 = red    
;                     2 = green  
;                     3 = blue   
;                     4 = cyan   
;                     5 = magenta
;                     6 = yellow
;                     7 = white
;           scaled -- set this keyword to draw circles which will dynamically
;                     scale with the zoom factor of the ATV image.  If not
;                     set, the circles will be drawn with an absolute radius
;                     (in pixels) as specified, regardless of the zoom state
;                     of the ATV image.
; PROCEDURE:  call ATV routine ATVPLOT, either to plot points with user-defined
;             circular symbol, or to crate circular overplots around each
;             selected point (depending on /SCALED keyword; see Notes).
; NOTES/SIDE EFFECTS: (1) setting /SCALED will cause
;                         ATV to draw each circle as an individual overplot,
;                         which could cause the MAXPLOTS limit (maximum number
;                         of overplots allowed in ATV, nominally 5000 in ATV
;                         1.5) to be quickly reached.
;                     (2) if /SCALED is not set, then the USERSYM procedure
;                         is used to define the circular plot symbols;
;                         subsequent calls to ATVCIRCLE (or USERSYM) will
;                         cause all USERSYM symbols in ATV to be redrawn
;                         with the current USERSYM, anytime the ATV image
;                         window is redrawn.
;                     (3) the USERSYM procedure creates plot symbols in
;                         character-sized units, so sizing in pixels is
;                         only approximate when the /SCALED keyword is not set.
;                     (4) the ATV routine ATVERASE erases overplots in the ATV
;                         image window:
;                         IDL> atverase     ;erase all overplots
;                         IDL> atverase,4   ;erase last 4 overplots
; MODIFICATION HISTORY:  Written by N. Cunningham, Univ. of Colorado, July 2005
;-

on_error,2

if n_params() ne 3 then begin
	print, 'syntax:    atvcircle, radius, x, y [, color=, /scaled]'
	return
endif
ncircs=n_elements(x)
if n_elements(y) ne ncircs then begin
	print, 'ATVCIRCLE -- x and y must have equal number of elements'
	print, '             Quitting...'
	return
endif
if size(x,/n_dimensions) eq 0 then x=make_array(1,value=x)
if size(y,/n_dimensions) eq 0 then y=make_array(1,value=y)
if n_elements(color) ne 0 then begin
	if size(color,/tname) eq 'STRING' then begin
		case strupcase(color) of
			'BLACK': color=0
			'RED':   color=1
			'GREEN': color=2
			'BLUE' : color=3
			'CYAN': color=4
			'MAGENTA': color=5
			'YELLOW': color=6
			'WHITE': color=7
			ELSE: begin
				print, "ATVCIRCLE -- Unrecognized color:  '"+color+"'"
				print, "             Accepted colors are: 'black', 'red', 'green', 'blue',"
				print, "                                  'cyan', 'magenta', 'yellow', 'white'"
				print, '             Quitting...'
				return
			end
		endcase
	endif
endif else color=1
npts=48
angs=findgen(npts+1)/float(npts)*2.*!pi
xsym=radius*cos(angs)
ysym=radius*sin(angs)
if keyword_set(scaled) then begin
	xplt=rebin(x,ncircs,npts+1)+transpose(rebin(xsym,npts+1,ncircs))
	yplt=rebin(y,ncircs,npts+1)+transpose(rebin(ysym,npts+1,ncircs))
	for i=0,ncircs-1 do atvplot,xplt[i,*],yplt[i,*],color=color,_extra=extra
endif else begin
	usersym,xsym/3.,ysym/3.,_extra=extra	;factor of 3 to get to pixel size
	atvplot,x,y,psym=8,color=color,_extra=extra
endelse

end
